Tips on USB driver matching for Mac OS X

Q: I can't get my kernel driver to match against my USB Device. What's wrong?

A: There could be many things causing your driver not to match. The most common mistake is an incorrect combination of property keys in your 'Info.plist' file. Matching is based on the USB Common Class Specification. The IOUSBFamily in conjunction with I/O Kit will use a probe score to determine the best candidate for a particular device. The following tables show the probe scores obtained by specifying the corresponding keys in your drivers 'Info.plist' file. Never add extra keys, because it might prevent your driver from matching. Only use the key combinations below.

USB Device

Keys	Comments	Score
idVendor + idProduct + bcdDevice		100000
idVendor + idProduct		90000
idVendor + bDeviceSubClass + bDeviceProtocol	Only if bDeviceClass is 0xFF.	80000
idVendor + bDeviceSubClass	Only if bDeviceClass is 0xFF.	70000
bDeviceClass + bDeviceSubClass + bDeviceProtocol	Only if bDeviceClass is not 0xFF.	60000
bDeviceClass + bDeviceSubClass	Only if bDeviceClass is not 0xFF.	50000

USB Interfaces

Keys	Comments	Score
idVendor + idProduct + bInterfaceNumber + bConfigurationValue + bcdDevice		100000
idVendor + idProduct + bInterfaceNumber + bConfigurationValue		90000
idVendor + bInterfaceSubClass + bInterfaceProtocol	Only if bInterfaceClass is 0xFF.	80000
idVendor + bInterfaceSubClass	Only if bInterfaceClass is 0xFF.	70000
bInterfaceClass + bInterfaceSubClass + bInterfaceProtocol	Only if bInterfaceClass is not 0xFF	60000
bInterfaceClass + bInterfaceSubClass	Only if bInterfaceClass is not 0xFF	50000

Make sure you use the correct combination depending on if you're matching against a USB Interface or a USB Device. If there exists two drivers that can control a particular device, the one with the highest probe score will win.

If your driver still fails to load, you may need to add an 'OSBundleRequired' key to your 'Info.plist' file along with the correct value so the system knows to load your driver early in the boot process. If you're doing a mouse or keyboard driver, this key is a requirement in order to prevent the built-in USB mouse and keyboard drivers from matching against your device. For more information on loading KEXTs at boot time, please see the Loading Kernel Extensions at Boot Time document.

Also, make sure that the value for the 'CFBundleIdentifier' key in your personality is the same value as the 'CFBundleIdentifier' key for the driver. This is illustrated in the example 'Info.plist' file below...


	Listing 1. CFBundleIdentifier values must be the same in both the driver and the personality.

If your driver fails to load on Mac OS X 10.1 or greater, it may be because you didn't add an 'OSBundleLibraries' dictionary to your 'Info.plist' file. This dictionary is used to specify all the kernel extensions that your driver requires be loaded in order to function. This dictionary was optional in Mac OS X 10.0.x, but is now a requirement, and KEXTs without this dictionary will refuse to load. Please read the Mac OS X Kernel Extension release notes for more information regarding the 'OSBundleLibraries' dictionary.

If all else fails, you can add an 'IOKitDebug' key to your personality with a value of 65535, and when running on Mac OS X 10.1, the IOUSBFamily will print out debug information to /var/log/system.log which may help in tracking down what went wrong.

[Oct 02 2001]

Developer Documentation | Technical Notes | Development Kits | Sample Code